README: about the KDF9 emulator ee9, Version 3 


Contents 

Introduction 

A. Getting acquainted 

B. Getting started 

The ee9 emulator: what you get 

A. In the Documents directory 

B. In the Testing directory 

C. In the Source directory 

D. In the Build directory 

Simple Examples 

A. Running the Whetstone Algol system 

B. Compiling and running Usercode programs 

C. Running the Time Sharing Director 

Miscellaneous OS Issues 

A. POSIX environment 

B. Getting a GNAT Ada 2012 compiler 

C. The Usercode compiler, kal3 

Introduction 

A. Getting acquainted 

ee9, my KDF9 emulator, runs a variety of interesting and important KDF9 programs. Please report any bugs you find to 
me, using the address kdf 9@ f indlayw. plus . com, to help advance the development effort. 

The source code of ee9 is released under the terms of the GPU, version 3. 

The download packages for Intel Macs include binaries that run on 10.13 (macOS High Sierra), 10.12 (macOS 
Sierra), 10.11 (El Capitan), 10.10 (Yosemite), and 10.9 (Mavericks). Additional download packages include (perhaps 
older) binaries for other OS/hardware combinations. Mike Hore has provided a build of ee9 and kal3 for a PowerPC G5 
Mac running OS X 10.5 (Feopard). Bill Gallagher has provided builds for Intel x86_32 and x86_64 under Linux, for Intel 
x86_32 under Microsoft Windows, and for the ARM 11-based Raspberry Pi under Raspbian Linux. 

These distributions can be found at: 

http;//www.findlayw.plus.com/KDF9/emulation/ 

B. Getting started 

You can verify the correct operation of my binary, or a port to another platform, by running (in Testing) the command: 

./ee9_self_test 

To be honest, this checks that your ee9 implementation gives the same results as mine, on a variety of Usercode and 
Whetstone Algol programs. It runs a set of test cases and allows you to compare expected and actual outputs and 
execution digital signatures (these are hashes of the register values at the end of each instruction-execution). It 
automatically compares its results file with a file containing the results from a run on my own computer, taken to be the 
standard of correctness. If your ee9 passes these tests we can safely assume that it is working as well as mine. 

The ee9 emulator: what you get 
A. In the Documents directory: 

1. A guide to using ee9: ‘Users Guide for ee9 . pdf ’: read this document first! 

2. A ‘HOWTO ' file that gives instruction on the operating procedures to be followed for compiling and executing 
both Usercode and Whetstone Algol (Walgol) programs 

3. Two papers by me, documenting the KDF9’s hardware and software: 

‘The English Electric KDF9.pdf’and ‘The Hardware of the KDF9.pdf’ 

4. Two text files, ‘WAlgol Translator-listing . txt’ and ‘WAlgol Controller-listing . txt’, 
that contain the kal3 compilation listings of those components of the Whetstone Algol system 

5. A list of all the error numbers generated by the Whetstone Translator and Controller: 

‘Walgol Error Numbers.pdf’ 

6. A file, ‘ee9 Release History. pdf’, that describes the amendment history of all ee9 releases to date 

7. Afile, ‘ee9 Implementation Overview.pdf’, that gives a synoptic account of the program structure of 
ee9, intended for those interested in maintaining or modifying it 
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B. In the Testing directory: 

1. An Algol subdirectory, containing Whetstone Algol 60 source-program and data files 

2. An Assembly subdirectory, containing Usercode assembly-language source program files and their data files 

3. A Binary subdirectory, containing KDF9 machine code programs for: 

a. The Whetstone Translator (compiler): KMW02 01—UPU 

b. The Whetstone Controller (byte code interpreter): KMW0301--UPU 

c. The EE Time Sharing Director (KDF9 OS): KKT4 0E007UPU 

d. Programs compiled from the Assembly subdirectory 

4. A collection of files to represent the KDF9’s I/O devices; for example: LPO , TR1, and so on 

5. An executable binary of kal3 , David Holdsworth’s new Usercode compiler 

6. UNIX shell scripts to facilitate running kal3 , KDF9 object programs, the Whetstone Algol system, 

and the Time Sharing Director. 

7. An executable binary of my KDF9 emulator: ee9 

8. A small set of shell files to implement a basic self-checking process for ee9: 

ee9_self_test,ee9_test_case, and ee9_test_run 

9. A text file containing the results of running ee9_self_test on my own computer, used as a comparator for 
its own results: ee9_good_test_case_log. txt 

10. The utility programs a_block and a2b 

C. In the Source directory: 

Complete Ada 2012 source code is provided. It should compile without errors and without warning messages. For 
Windows only, there is also a short routine, written in C, to fetch a value defined in a C header file in Cygwin. 

D. In the Build directory: 

1. A shell file to build ee9, mk9 , plus tidy and pk9 which package-up a distribution 

2. GNAT option files for alternative builds of ee9: adc-* . adc 

3. The option file used to generate the distributed binary of ee9: gnat . adc 

4. The compilation listing of that build: komlog . ada 

5. The shell file to9, which compiles and runs to_9_f rom_1934 to convert from ICT 1934 to KDF9 plotter code 
Simple Examples 

These examples assume that the current working directory is Testing. It is convenient to have a terminal window open 
in the Testing directory, if you will be making multiple runs of ee9. If you further put Testing in your shell PATH 
variable, you will be able to run the commands supplied in Testing with no need for the ‘. /’ prefix shown in the 
examples below. The shell commands tsd, whet, nine and nine_test conveniently abbreviate common usages of 
ee9. They invoke, in turn, simpler commands that you may prefer to use directly. For much more detailed help with this, 
see the HOWTO file in the Documents directory. 

A. To run the Whetstone system on the Algol 60 program Algol/sieve. a60: 

./whet SIEVE 

B. To compile Usercode/HiGuys . k3, and run it in fast mode (N.B.: HIGUYS needs no data file, hence the ‘-’): 

./ucc HIGUYS 
./nine HIGUYS - f 

C. To execute a run of Director in trace mode: 

./tsd t 
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Miscellaneous OS Issues 

A. POSIX ENVIRONMENT 

You may benefit from ensuring that your system is set up to use the Latin-1 character set. You can find out by issuing the 
bash command: 

set | grep LANG 

If the output does not contain ‘IS08859-1’ then you need to reset your locale and character set. The bash command: 
export LANG=en_GB.IS08859-1 

(or its equivalent using another shell) will achieve this for UK users. (This is not relevant to Windows.) 

If you are using a version of Windows pre-10, and you want to run the shell command files that I provide to make life 
with ee9 a little easier, or if you want to compile your own version of ee9, then you will need to install Cygwin, which 
provides a POSIX command set and API for Windows, including a bash-compatible shell named dash. A suitable 
version can be obtained from: 


http://www.cyqwin.com/install.html 

B. Getting a GNAT Ada 2012 compiler 

If you want to build ee9 yourself, you will need a recent version of GNAT, the GNU Ada compiler, because ee9 is now 
written in Ada 2012. Current versions of GNAT for several systems, including macOS, Linux, and Windows, can be 
obtained with a GPL licence from AdaCore at: 

http://libre.adacore.com/libre 

On macOS you may also need to download and install Apple’s BSD command-line utilities. Use the command: 

xcode-select --install 

N.B. You may find it necessary to repeat this step after installing a new version of the operating system. You certainly will 
if an attempt to compile a C program such as kal3 complains about the absence of the header file <stdlib. h>. 

A possibility if you have a PowerPC (G3/G4/G5) Mac running OS X Leopard or Tiger is: 

http://sourceforge.net/projects/qnuada/files/GNAT GPL%20Mac%20QS%2OX/2009-tiqer-ppc/ 

Old compilers like this do not support Ada 2012, so you will need to be content with an older, Ada 2005, version of ee9. 

GNAT is supported by Raspbian on the Raspberry Pi, so use the apt-get utility to fetch and install it, thus: 

apt-get update 
apt-get install gnat 

Raspbian Ada compilers since the Debian Stretch release support Ada 2012, but earlier versions may not, so you may 
need to be content with an old, Ada 2005, version of ee9. 

There are compilers for other hardware/software combinations at: 

https://gcc.gnu.org 

If your system is not one of these, you may find pointers to a suitable port at the Ada Programming Wikibook. If none of 
these meets your needs, try asking in the comp. lang. ada USENET newsgroup. People there are very helpful and may 
already have just the port you need. As a last resort, you may be able to compile your own version of GNAT; the source 
code is available for download from the Free Software Foundation. (Please don’t ask me for help with this; I have 
absolutely no idea how to go about it!) 

C. The Usercode compiler, kal3 

David Holdsworth’s kal3 (a new KDF9 Usercode compiler) is included in both source and binary forms with the 
appropriate download packages. It is trivial to (re-)compile kal3, using the kal3 option of mk9. 

D. Another KDF9 emulator, kdf 9 

David Holdsworth’s kdf 9 (a more basic KDF9 emulator than ee9) is included in both source and binary forms with the 
appropriate download packages. It is trivial to (re-)compile kdf 9, using the kdf 9 option of mk9. 
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